feat: generalize $ref resolver + shared $ref-aware azure.yaml edit helper#8777
Merged
Conversation
huimiu
requested review from
JeffreyCA,
glharper,
therealjohn,
trangevi and
trrwilson
as code owners
huimiu
changed the title
Contributor
There was a problem hiding this comment.
Pull request overview
This PR extends the existing $ref include resolver contract to explicitly cover the “separate-services” azure.yaml shape, and adds a shared $ref-aware, comment-preserving YAML edit helper so read/write behavior stays consistent across Foundry-related commands and extensions.
Changes:
- Document the generalized
ResolveFileRefscontract to cover service-entry top-level$ref, deployments array-item$ref, and nested$refrecursion. - Add resolver test coverage for the new documented shapes (including shallow sibling overlay behavior).
- Introduce
includes_edit.go(YAMLDocument) for comment/order-preserving edits, with$ref-aware inline-vs-ref-file targeting and corresponding tests.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| cli/azd/extensions/azure.ai.agents/internal/project/includes.go | Updates resolver documentation to describe separate-services $ref shapes and contract. |
| cli/azd/extensions/azure.ai.agents/internal/project/includes_test.go | Adds tests for service-entry-level and deployments array-item $ref resolution + overlays. |
| cli/azd/extensions/azure.ai.agents/internal/project/includes_edit.go | Adds a $ref-aware YAML editing helper that preserves comments/key order and can write inline or into split files. |
| cli/azd/extensions/azure.ai.agents/internal/project/includes_edit_test.go | Adds tests for round-trip stability and for inline/ref-file edit behavior aligning with ResolveFileRefs. |
This was referenced Jun 23, 2026
trangevi
approved these changes
Jun 23, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Part of #8775 · Design spec PR #8590 (
docs/specs/unify-azure-yaml/spec.md§2.4).Base branch is
huimiu/foundry-azure-yaml(the Foundryazure.yamlintegration branch). This PR is intentionally independent of #8675.What
PR3 of the "unify Foundry config in
azure.yaml" follow-up.Resolver generalization (
includes.go— docs + tests only)The
$refresolver from #8627 already resolves$refat any map/sequence node, so the separate-services shapes need no new resolution logic — only a generalized documented contract and coverage:$ref(top-level inline map, besidehost:/ the service key, which core strips).$refon the project service.project/instructions/ nested$ref(already implemented).Shared
$ref-aware YAML edit helper (includes_edit.go— new)A comment-preserving writer that the #8049 composition commands also use, so reads and writes of
$refentries agree:YAMLDocumentload / parse / save / bytes — braydonk round-trip with two-space indent and block-scalar style, matching how azd core writesazure.yaml.ServiceEntry(name, create),EntryRef(entry),SetServiceField(name, key, value, EditTarget).EditInlineoverlays a key beside$ref(the §2.4 default);EditRefFilefollows the$refinto the split file (path resolved with the resolver's shared logic), falling back to inline when the entry is not$ref-backed.pkg/yamlnodefor node ops and the resolver'srefKey/refTargetPath, so the writer and resolver agree on what a$refentry is and where it points.Out of scope
Wiring the resolver into each provider's parse path (rides with PR2), remote URL
$reffetching, and JSON-Schema validation of loaded entries. No azd-core changes; no dependency on #8675.Tests
go test ./internal/project/...$ref(+ overlay), projectdeployments:array-item$ref(+ inline item, + overlay).$refdetection, inline overlay + read-back agreement viaResolveFileRefs, in-place update (comment preserved),EditRefFilesplit-file write, non-$reffallback, and missing ref-file error.gofmt -s,golangci-lint, andcspellare clean.